home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer)…68k, x86, SPARC, PA-RISC] / NeXTSTEP 3.3 Dev Intel.iso / NextDeveloper / Headers / foundation / NSArray.h < prev    next >
Text File  |  1994-05-13  |  8KB  |  226 lines
  1. /*    NSArray.h
  2.     Basic dynamic array
  3.       Copyright 1993, 1994, NeXT, Inc.
  4.     NeXT, March 1993
  5. */
  6.  
  7. #import <foundation/NSString.h>
  8.  
  9. /* This module implement the 'array' concept.  Featuring:
  10.     - arrays are always dynamic (resize themselves by doubling when they reach a certain maximum), so that callers never have to think about allocation;
  11.     - support read only arrays;
  12.     - embeds various conveniences and algorithms (e.g. sort);
  13.     
  14.    Generic coding behavior is supplied
  15.     - it preserves class and calls initWithObjects:count:
  16.     - immutable arrays are distributed bycopy with their elements also bycopy
  17.     - mutable arrays are distributed by reference unless asked bycopy
  18. */
  19.  
  20. obsolete enum {NSNotInArray = 0x7fffffff}; // to be obsoleted soon
  21.  
  22. /***************    Read Only Abstract Class        ***********/
  23.  
  24. @interface NSArray:NSObject <NSCopying, NSMutableCopying>
  25. /* NOTES:
  26.     -copyWithZone: and -copy guarantee an immutable returned value;
  27.         elements are recursively copied with -copyWithZone:
  28.     -isEqual: checks that argument is an NSArray;
  29.     If conforming, each item is compared using isEqual:;
  30.     -hash is such that [x isEqual:y] => [x hash] == [y hash];    
  31.      */
  32.  
  33. - (unsigned)count;
  34.     /* Number of items in the array (NOT the maximum capacity of the array) */
  35.     
  36. - objectAtIndex:(unsigned)index;
  37.     /* Raises if index out of bounds;
  38.     Clients can expect this method to be fast, in O(1) */
  39.     
  40. @end
  41.  
  42. @interface NSArray (NSExtendedArray)
  43.  
  44. - (unsigned)indexOfObjectIdenticalTo:anObject;
  45.     /* Performs search on the array for candidate;
  46.     pointer equality is used;
  47.     Return NSNotFound iff not found */
  48.  
  49. - (unsigned)indexOfObject:anObject;
  50.     /* Performs search on the array for candidate;
  51.     isEqual: equality is used;
  52.     Return NSNotFound iff not found */
  53.  
  54. - (BOOL)containsObject:anObject;
  55.     /* short cut for indexOfObject: (isEqual: is used) */
  56.     
  57. - (BOOL)isEqualToArray:(NSArray *)otherArray;
  58.     /* Compares 2 arrays for exact match;
  59.     Uses isEqual: as the comparison predicate; */
  60.  
  61. - lastObject;
  62.     /* Returns nil if none */
  63.  
  64. - (void)makeObjectsPerform:(SEL)aSelector;
  65. - (void)makeObjectsPerform:(SEL)aSelector withObject:argument;
  66.     
  67. - (NSArray *)sortedArrayUsingSelector:(SEL)comparator;
  68.     /* Returns a sorted array of references;
  69.     Ascending sort.  Sort guarantees at most N*LOG(N) comparisons;
  70.     (for N=2**P, at most (2**P)*(P-1)+1 comparisons)
  71.     Performs comparator with 2 items to be compared ([item1 comparator:item2]);
  72.     Comparison should return <0 if ascending >0 if descending 0 if same */
  73.     
  74. - (NSArray *)sortedArrayUsingFunction:(int (*)(id, id, void *))comparator context:(void *)context;
  75.     /* Same except calls comparator with 3 arguments: 2 items to be compared and parameter */
  76.  
  77. - (NSString *)componentsJoinedByString:(NSString *)separator;
  78.     /* The reverse of the componentsSeparatedByString: method in NSString.
  79.     From the various parts, builds a complete string, with the separator
  80.     in between each string. If sent to an empty array, "" will be returned.
  81.     It is an error for the array to contain any elements that aren't NSStrings. */
  82.  
  83. - firstObjectCommonWithArray:(NSArray *)otherArray;
  84.     /* Returns the first object in the receiver which occurs in the argument. */
  85.  
  86. - (NSArray *)subarrayWithRange:(NSRange)range;
  87.     /* returns the restriction of self to range */
  88.  
  89. - (NSEnumerator *)objectEnumerator;
  90.     /* Returns an enumerator object to cycle through the contents,
  91.     starting at the 0th element.
  92.     Updates should not be done during enumeration
  93.     To use:
  94.         NSEnumerator *enumerator = [collection objectEnumerator];
  95.     id object;
  96.     while (object = [enumerator nextObject]) {
  97.         ... 
  98.     }
  99.     */
  100.  
  101. - (NSEnumerator *)reverseObjectEnumerator;
  102.     /* Returns an enumerator that enumerates objects starting at lastObject */
  103.  
  104. - (NSString *)description;
  105.     /* Convert to a string, using the "PropertyList" format */
  106.  
  107. - (NSString *)descriptionWithIndent:(unsigned)level;
  108.     /* Convert to a string, using the "PropertyList" format;
  109.     Indent is for human-readibility;
  110.     level==0 means top level; level==1 => 4 spaces */
  111.  
  112. @end
  113.  
  114. /***************    Mutable Abstract Class        ***************/
  115.  
  116. @interface NSMutableArray: NSArray
  117.  
  118. /* Note: Only the 3 first methods are necessary for the Array abstraction.  However, in order to enable subclasses to meaningfully implement certain functions (i.e. notification), all classes implementing the NSMutableArray should implement all 5 methods, and no method should call recursively any of the others */
  119.  
  120. - (void)addObject:anObject;
  121.     /* Appends element at end of array; Resizes if necessary;
  122.     -retain is applied to the object inserted;
  123.     If object is nil an exception is raised;
  124.     Clients can expect this method to be fast, in O(1) */
  125.     
  126. - (void)replaceObjectAtIndex:(unsigned)index withObject:anObject;
  127.     /* Replaces any existing item;
  128.     If object is nil an exception is raised.
  129.     The object inserted in the array is the result of [object retain] 
  130.     and -release is applied to previous element;
  131.     Clients can expect this method to be fast, in O(1) */
  132.     
  133. - (void)removeLastObject;
  134.     /* Removes from array; Raises if applied on an empty list.
  135.     Applies -release to removed object;
  136.     Clients can expect this method to be fast, in O(1) */    
  137.     
  138. - (void)insertObject:anObject atIndex:(unsigned)index;
  139.     /* Shifts the items after index to allow insertion;
  140.     The object inserted in the array is the result of [object retain]
  141.     Attention: this method is slow: only O(count) time is guaranteed */
  142.     
  143. - (void)removeObjectAtIndex:(unsigned)index;
  144.     /* Recompacts the array after item has been removed;
  145.     Applies -release to removed object;
  146.     Attention: this method is slow: only O(count) time is guaranteed */
  147.     
  148. @end
  149.  
  150. @interface NSMutableArray (NSExtendedMutableArray)
  151.     
  152. - (void)removeObjectIdenticalTo:anObject;
  153.     /* Removes all occurrences of candidate */
  154.  
  155. - (void)removeObject:anObject;
  156.     /* Removes all occurrences of candidate */
  157.  
  158. - (void)removeAllObjects;
  159.     /* Removes all object froms the array; 
  160.     Applies -release to each removed object */
  161.  
  162. - (void)addObjectsFromArray:(NSArray *)otherArray;
  163.     /* adds each element in otherArray */
  164.  
  165. - (void)removeObjectsFromIndices:(unsigned *)indices numIndices:(unsigned)count;
  166.     /* Speed up of removeObjectAtIndex: for batches of indices;
  167.     This method does not distribute and therefore should be used sparingly */
  168.  
  169. - (void)removeObjectsInArray:(NSArray *)otherArray;
  170.     /* Assumes that all elements in otherArray respond to -hash and -isEqual:, 
  171.     in order to very efficiently remove large sets of objects;
  172.     This method does not distribute and therefore should be used sparingly */
  173.  
  174. - (void)sortUsingFunction:(int (*)(id, id, void *))compare context:(void *)context;
  175.     /* In place sort; O(N * LOG(N)) */
  176.  
  177. @end
  178.  
  179. /***************    Array creation        ***************/
  180.  
  181. @interface NSArray (NSArrayCreation)
  182.  
  183. + allocWithZone:(NSZone *)zone;
  184.     /* Create an uninitialized instance of a concrete array;
  185.     substitutes a concrete class if called with NSArray;
  186.     +alloc can also be used to that effect */
  187.  
  188. + array;
  189.     /* Creates an empty autoreleased array */
  190.  
  191. + arrayWithObject:anObject;
  192.     /* convenience to create an autoreleased array with just 1 element */
  193.  
  194. + arrayWithObjects:firstObj, ...;
  195.     /* convenience to create an autoreleased array */
  196.  
  197. - initWithObjects:(id *)objects count:(unsigned)count;
  198.     /* Objects are retained;
  199.     Designated initializer for immutable arrays */
  200.  
  201. - initWithObjects:firstObj, ...;
  202.     /* Vararg list terminated with nil. */
  203.  
  204. - initWithArray:(NSArray *)array;
  205.     /* Performs -retain: for each item in array */
  206.  
  207. @end
  208.  
  209. /***************    Mutable Array creation        ***************/
  210.  
  211. @interface NSMutableArray (NSMutableArrayCreation)
  212.  
  213. + allocWithZone:(NSZone *)zone;
  214.     /* Create an uninitialized instance of a concrete mutable array;
  215.     substitutes a concrete class if called with NSMutableArray;
  216.     +alloc can also be used to that effect;
  217.     -dealloc empties array using -removeAllObjects before de-allocating */
  218.  
  219. + arrayWithCapacity:(unsigned)numItems;
  220.     /* Creates an autoreleased mutable array */
  221.  
  222. - initWithCapacity:(unsigned)numItems;
  223.     /* Designated initializer for mutable arrays */
  224.  
  225. @end
  226.